From cf5df3fd7bf7521978e7b64207bc4f407d230d00 Mon Sep 17 00:00:00 2001 From: Robb Romans Date: Fri, 2 Dec 2005 14:29:25 -0700 Subject: [PATCH] Reorg patch 1 to match http://wiki.xensource.com/xenwiki/Xen3DocsToDo First patch to reorganize the manual to match the structure in the Xen3DocsToDo Wiki entry. Incorporates a patch from Nivedita Singhvi to clean up the Further Support Chapter. Signed-off-by: Robb Romans --- docs/src/user.tex | 110 ++++++++++------------- docs/src/user/debian.tex | 2 +- docs/src/user/debugging.tex | 25 ++++++ docs/src/user/{redhat.tex => fedora.tex} | 2 +- docs/src/user/further_support.tex | 52 +++++++++++ docs/src/user/gentoo.tex | 3 + docs/src/user/installation.tex | 70 +++++++-------- docs/src/user/introduction.tex | 4 +- docs/src/user/known_problems.tex | 3 + docs/src/user/monitoring_xen.tex | 3 + docs/src/user/{build.tex => options.tex} | 23 +---- docs/src/user/rhel.tex | 3 + docs/src/user/suse.tex | 3 + docs/src/user/testing.tex | 3 + 14 files changed, 181 insertions(+), 125 deletions(-) create mode 100644 docs/src/user/debugging.tex rename docs/src/user/{redhat.tex => fedora.tex} (97%) create mode 100644 docs/src/user/further_support.tex create mode 100644 docs/src/user/gentoo.tex create mode 100644 docs/src/user/known_problems.tex create mode 100644 docs/src/user/monitoring_xen.tex rename docs/src/user/{build.tex => options.tex} (88%) create mode 100644 docs/src/user/rhel.tex create mode 100644 docs/src/user/suse.tex create mode 100644 docs/src/user/testing.tex diff --git a/docs/src/user.tex b/docs/src/user.tex index 6f0c78952b..082ecb8352 100644 --- a/docs/src/user.tex +++ b/docs/src/user.tex @@ -29,10 +29,10 @@ \end{center} {\bf DISCLAIMER: This documentation is currently under active - development and as such there may be mistakes and omissions --- - watch out for these and please report any you find to the - developers' mailing list. Contributions of material, suggestions - and corrections are welcome.} + development and as such there may be mistakes and omissions --- watch + out for these and please report any you find to the developers' + mailing list. Contributions of material, suggestions and corrections + are welcome.} \vfill \cleardoublepage @@ -60,103 +60,85 @@ \setstretch{1.1} -\part{Introduction and Tutorial} +\part{Introduction} %% Chapter Introduction moved to introduction.tex \include{src/user/introduction} -%% Chapter Installation moved to installation.tex -\include{src/user/installation} -%% Chapter Starting Additional Domains moved to start_addl_dom.tex -\include{src/user/start_addl_dom} +\part{Installation} -%% Chapter Domain Management Tools moved to domain_mgmt.tex -\include{src/user/domain_mgmt} +%% Chapter Basic Installation +\include{src/user/installation} -%% Chapter Domain Filesystem Storage moved to domain_filesystem.tex -\include{src/user/domain_filesystem} +%% Chapter Installing Xen on Debian +\include{src/user/debian} +%% Chapter Installing Xen on Fedora Core +\include{src/user/fedora} +%% Chapter Installing Xen on Gentoo Linux +\include{src/user/gentoo} -\part{User Reference Documentation} +%% Chapter Installing Xen on Red Hat Enterprise Linux (RHEL) +\include{src/user/rhel} -%% Chapter Control Software moved to control_software.tex -\include{src/user/control_software} +%% Chapter Installing Xen on SuSE or SuSE SLES +\include{src/user/suse} -%% Chapter Domain Configuration moved to domain_configuration.tex -\include{src/user/domain_configuration} -%% Chapter Securing Xen -\include{src/user/securing_xen} +\part{Configuration and Management} -%% Chapter Build, Boot and Debug Options moved to build.tex -\include{src/user/build} +%% Chapter Starting Additional Domains +\include{src/user/start_addl_dom} +%% Chapter Domain Management Tools +\include{src/user/domain_mgmt} -\chapter{Further Support} +%% Chapter Domain Filesystem Storage +\include{src/user/domain_filesystem} -If you have questions that are not answered by this manual, the -sources of information listed below may be of interest to you. Note -that bug reports, suggestions and contributions related to the -software (or the documentation) should be sent to the Xen developers' -mailing list (address below). +%% Chapter Domain Configuration +\include{src/user/domain_configuration} +%% Chapter Securing Xen +\include{src/user/securing_xen} -\section{Other Documentation} -For developers interested in porting operating systems to Xen, the -\emph{Xen Interface Manual} is distributed in the \path{docs/} -directory of the Xen source distribution. +\part{Troubleshooting} -% Various HOWTOs are available in \path{docs/HOWTOS} but this content -% is being integrated into this manual. +%% Chapter Monitoring Xen +\include{src/user/monitoring_xen} +%% Chapter Debugging and Tracing +\include{src/user/debugging} -\section{Online References} +%% Chapter Known Problems +\include{src/user/known_problems} -The official Xen web site is found at: -\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/} -\end{quote} +%% Chapter Testing Xen +\include{src/user/testing} -This contains links to the latest versions of all online -documentation, including the latest version of the FAQ. +\part{Reference Documentation} -\section{Mailing Lists} +%% Chapter Control Software +\include{src/user/control_software} -There are currently four official Xen mailing lists: +%% Chapter Build and Boot Options +\include{src/user/options} -\begin{description} -\item[xen-devel@lists.xensource.com] Used for development - discussions and bug reports. Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-devel}} -\item[xen-users@lists.xensource.com] Used for installation and usage - discussions and requests for help. Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-users}} -\item[xen-announce@lists.xensource.com] Used for announcements only. - Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-announce}} -\item[xen-changelog@lists.xensource.com] Changelog feed - from the unstable and 2.0 trees - developer oriented. Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-changelog}} -\end{description} +%% Chapter Further Support +\include{src/user/further_support} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \appendix -%% Chapter Installing Xen / XenLinux on Debian moved to debian.tex -\include{src/user/debian} - -%% Chapter Installing Xen on Red Hat moved to redhat.tex -\include{src/user/redhat} - %% Chapter Glossary of Terms moved to glossary.tex \include{src/user/glossary} - - \end{document} diff --git a/docs/src/user/debian.tex b/docs/src/user/debian.tex index 898e515041..9f76fd5e07 100644 --- a/docs/src/user/debian.tex +++ b/docs/src/user/debian.tex @@ -1,4 +1,4 @@ -\chapter{Installing Xen / XenLinux on Debian} +\chapter{Installing Xen on Debian} The Debian project provides a tool called \path{debootstrap} which allows a base Debian system to be installed into a filesystem without diff --git a/docs/src/user/debugging.tex b/docs/src/user/debugging.tex new file mode 100644 index 0000000000..2ed70039c0 --- /dev/null +++ b/docs/src/user/debugging.tex @@ -0,0 +1,25 @@ +\chapter{Debugging and Tracing} + +\section{Debugging} +\label{s:keys} + +Xen has a set of debugging features that can be useful to try and figure +out what's going on. Hit ``h'' on the serial line (if you specified a baud +rate on the Xen command line) or ScrollLock-h on the keyboard to get a +list of supported commands. + +If you have a crash you'll likely get a crash dump containing an EIP +(PC) which, along with an \path{objdump -d image}, can be useful in +figuring out what's happened. Debug a Xenlinux image just as you would +any other Linux kernel. + +%% We supply a handy debug terminal program which you can find in +%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should +%% be built and executed on another machine that is connected via a +%% null modem cable. Documentation is included. Alternatively, if the +%% Xen machine is connected to a serial-port server then we supply a +%% dumb TCP terminal client, {\tt xencons}. + +\section{Tracing} + +Placeholder. \ No newline at end of file diff --git a/docs/src/user/redhat.tex b/docs/src/user/fedora.tex similarity index 97% rename from docs/src/user/redhat.tex rename to docs/src/user/fedora.tex index 717b9197de..a0975aed19 100644 --- a/docs/src/user/redhat.tex +++ b/docs/src/user/fedora.tex @@ -1,4 +1,4 @@ -\chapter{Installing Xen / XenLinux on Red~Hat or Fedora Core} +\chapter{Installing Xen on Red~Hat or Fedora Core} When using Xen / XenLinux on a standard Linux distribution there are a couple of things to watch out for: diff --git a/docs/src/user/further_support.tex b/docs/src/user/further_support.tex new file mode 100644 index 0000000000..77bc836b8f --- /dev/null +++ b/docs/src/user/further_support.tex @@ -0,0 +1,52 @@ +\chapter{Further Support} + +If you have questions that are not answered by this manual, the +sources of information listed below may be of interest to you. Note +that bug reports, suggestions and contributions related to the +software (or the documentation) should be sent to the Xen developers' +mailing list (address below). + + +\section{Other Documentation} + +For developers interested in porting operating systems to Xen, the +\emph{Xen Interface Manual} is distributed in the \path{docs/} +directory of the Xen source distribution. + + +\section{Online References} + +The official Xen web site is found at: +\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/} +\end{quote} + +This contains links to the latest versions of all online +documentation, including the latest version of the FAQ. + +Information regarding Xen is also available at the Xen Wiki at +\begin{quote} {\tt http://wiki.xensource.com/xenwiki/}\end{quote} +The Xen project uses Bugzilla as its bug tracking system. You'll find +the Xen Bugzilla at http://bugzilla.xensource.com/bugzilla/. + + +\section{Mailing Lists} + +There are several mailing lists that are used to discuss Xen related +topics. The most widely relevant are listed below. An official page of +mailing lists and subscription information can be found at \begin{quote} + {\tt http://lists.xensource.com/} \end{quote} + +\begin{description} +\item[xen-devel@lists.xensource.com] Used for development + discussions and bug reports. Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-devel}} +\item[xen-users@lists.xensource.com] Used for installation and usage + discussions and requests for help. Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-users}} +\item[xen-announce@lists.xensource.com] Used for announcements only. + Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-announce}} +\item[xen-changelog@lists.xensource.com] Changelog feed + from the unstable and 2.0 trees - developer oriented. Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-changelog}} +\end{description} diff --git a/docs/src/user/gentoo.tex b/docs/src/user/gentoo.tex new file mode 100644 index 0000000000..d8ff2e3c3e --- /dev/null +++ b/docs/src/user/gentoo.tex @@ -0,0 +1,3 @@ +\chapter{Installing Xen on Gentoo Linux} + +Placeholder. diff --git a/docs/src/user/installation.tex b/docs/src/user/installation.tex index b801c8d781..b6af54b640 100644 --- a/docs/src/user/installation.tex +++ b/docs/src/user/installation.tex @@ -1,9 +1,9 @@ -\chapter{Installation} +\chapter{Basic Installation} The Xen distribution includes three main components: Xen itself, ports of Linux and NetBSD to run on Xen, and the userspace tools required to manage a Xen-based system. This chapter describes -how to install the Xen~2.0 distribution from source. Alternatively, +how to install the Xen~3.0 distribution from source. Alternatively, there may be pre-built packages available as part of your operating system distribution. @@ -122,16 +122,16 @@ just contains the virtual ones. These are found in \path{dist/install/boot/} along with the image for Xen itself and the configuration files used during the build. -The NetBSD port can be built using: -\begin{quote} -\begin{verbatim} -# make netbsd20 -\end{verbatim}\end{quote} -NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch. -The snapshot is downloaded as part of the build process if it is not -yet present in the \path{NETBSD\_SRC\_PATH} search path. The build -process also downloads a toolchain which includes all of the tools -necessary to build the NetBSD kernel under Linux. +%The NetBSD port can be built using: +%\begin{quote} +%\begin{verbatim} +%# make netbsd20 +%\end{verbatim}\end{quote} +%NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch. +%The snapshot is downloaded as part of the build process if it is not +%yet present in the \path{NETBSD\_SRC\_PATH} search path. The build +%process also downloads a toolchain which includes all of the tools +%necessary to build the NetBSD kernel under Linux. To customize the set of kernels built you need to edit the top-level Makefile. Look for the line: @@ -169,7 +169,7 @@ kernel containing only virtual device drivers. %% currently), you'll need to enable devfs and devfs mount at boot %% time in the xen0 config. }} -\subsection{Custom XenLinux Builds} +\subsection{Custom Kernels} % If you have an SMP machine you may wish to give the {\tt '-j4'} % argument to make to get a parallel build. @@ -206,7 +206,7 @@ you may prefer these for your non-privileged domains. The ``0'' suffixed privileged versions can be used to boot the system, as well as in driver domains and unprivileged domains. -\subsection{Installing the Binaries} +\subsection{Installing Generated Binaries} The files produced by the build process are stored under the \path{dist/install/} directory. To install them in their default @@ -307,7 +307,7 @@ line with: \end{quote} This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1 -stop bit and no parity. Modify these parameters for your set up. +stop bit and no parity. Modify these parameters for your environment. One can also configure XenLinux to share the serial console; to achieve this append ``\path{console=ttyS0}'' to your module line. @@ -325,38 +325,38 @@ the serial line will require adding \path{ttyS0} to Users of the XenLinux 2.6 kernel should disable Thread Local Storage (TLS) (e.g.\ by doing a \path{mv /lib/tls /lib/tls.disabled}) before -attempting to boot a XenLinux kernel\footnote{If you boot without - first disabling TLS, you will get a warning message during the boot - process. In this case, simply perform the rename after the machine - is up and then run \texttt{/sbin/ldconfig} to make it take effect.}. -You can always reenable TLS by restoring the directory to its original -location (i.e.\ \path{mv /lib/tls.disabled /lib/tls}). +attempting to boot a XenLinux kernel\footnote{If you boot without first + disabling TLS, you will get a warning message during the boot process. + In this case, simply perform the rename after the machine is up and + then run \path{/sbin/ldconfig} to make it take effect.}. You can +always reenable TLS by restoring the directory to its original location +(i.e.\ \path{mv /lib/tls.disabled /lib/tls}). The reason for this is that the current TLS implementation uses -segmentation in a way that is not permissible under Xen. If TLS is -not disabled, an emulation mode is used within Xen which reduces -performance substantially. +segmentation in a way that is not permissible under Xen. If TLS is not +disabled, an emulation mode is used within Xen which reduces performance +substantially. We hope that this issue can be resolved by working with Linux -distributions to implement a minor backward-compatible change -to the TLS library. +distributions to implement a minor backward-compatible change to the TLS +library. \section{Booting Xen} -It should now be possible to restart the system and use Xen. Reboot -and choose the new Xen option when the Grub screen appears. +It should now be possible to restart the system and use Xen. Reboot and +choose the new Xen option when the Grub screen appears. -What follows should look much like a conventional Linux boot. The -first portion of the output comes from Xen itself, supplying low level -information about itself and the underlying hardware. The last -portion of the output comes from XenLinux. +What follows should look much like a conventional Linux boot. The first +portion of the output comes from Xen itself, supplying low level +information about itself and the underlying hardware. The last portion +of the output comes from XenLinux. -You may see some errors during the XenLinux boot. These are not +You may see some errors during the XenLinux boot. These are not necessarily anything to worry about --- they may result from kernel configuration differences between your XenLinux kernel and the one you usually use. When the boot completes, you should be able to log into your system as -usual. If you are unable to log in, you should still be able to -reboot with your normal Linux kernel. +usual. If you are unable to log in, you should still be able to reboot +with your normal Linux kernel. diff --git a/docs/src/user/introduction.tex b/docs/src/user/introduction.tex index fde66915a7..67c5368849 100644 --- a/docs/src/user/introduction.tex +++ b/docs/src/user/introduction.tex @@ -1,7 +1,7 @@ \chapter{Introduction} -Xen is a \emph{paravirtualising} virtual machine monitor (VMM), or +Xen is a \emph{paravirtualizing} virtual machine monitor (VMM), or ``hypervisor'', for the x86 processor architecture. Xen can securely execute multiple virtual machines on a single physical system with close-to-native performance. The virtual machine technology @@ -139,4 +139,4 @@ sites. Xen 3.0 features greatly enhanced hardware support, configuration flexibility, usability and a larger complement of supported operating systems. This latest release takes Xen a step closer to becoming the -definitive open source solution for virtualisation. +definitive open source solution for virtualization. diff --git a/docs/src/user/known_problems.tex b/docs/src/user/known_problems.tex new file mode 100644 index 0000000000..dff5f0abe0 --- /dev/null +++ b/docs/src/user/known_problems.tex @@ -0,0 +1,3 @@ +\chapter{Known Problems} + +Problem One: No Known Problems Chapter. diff --git a/docs/src/user/monitoring_xen.tex b/docs/src/user/monitoring_xen.tex new file mode 100644 index 0000000000..231430dd62 --- /dev/null +++ b/docs/src/user/monitoring_xen.tex @@ -0,0 +1,3 @@ +\chapter{Monitoring Xen} + +Placeholder. diff --git a/docs/src/user/build.tex b/docs/src/user/options.tex similarity index 88% rename from docs/src/user/build.tex rename to docs/src/user/options.tex index 44e7c5b507..36a14b840d 100644 --- a/docs/src/user/build.tex +++ b/docs/src/user/options.tex @@ -1,4 +1,4 @@ -\chapter{Build, Boot and Debug Options} +\chapter{Build and Boot Options} This chapter describes the build- and boot-time options which may be used to tailor your Xen system. @@ -147,24 +147,3 @@ In addition to the standard Linux kernel boot options, we support: \end{center} The default is ttyS for dom0 and tty for all other domains. \end{description} - - -\section{Debugging} -\label{s:keys} - -Xen has a set of debugging features that can be useful to try and -figure out what's going on. Hit `h' on the serial line (if you -specified a baud rate on the Xen command line) or ScrollLock-h on the -keyboard to get a list of supported commands. - -If you have a crash you'll likely get a crash dump containing an EIP -(PC) which, along with an \path{objdump -d image}, can be useful in -figuring out what's happened. Debug a Xenlinux image just as you -would any other Linux kernel. - -%% We supply a handy debug terminal program which you can find in -%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should -%% be built and executed on another machine that is connected via a -%% null modem cable. Documentation is included. Alternatively, if the -%% Xen machine is connected to a serial-port server then we supply a -%% dumb TCP terminal client, {\tt xencons}. diff --git a/docs/src/user/rhel.tex b/docs/src/user/rhel.tex new file mode 100644 index 0000000000..bc40a24650 --- /dev/null +++ b/docs/src/user/rhel.tex @@ -0,0 +1,3 @@ +\chapter{Installing Xen on Red Hat Enterprise Linux (RHEL)} + +Placeholder. diff --git a/docs/src/user/suse.tex b/docs/src/user/suse.tex new file mode 100644 index 0000000000..8f66d2fc55 --- /dev/null +++ b/docs/src/user/suse.tex @@ -0,0 +1,3 @@ +\chapter{Installing Xen on SuSE or SuSE Linux Enterprise Server (SLES)} + +Placeholder. diff --git a/docs/src/user/testing.tex b/docs/src/user/testing.tex new file mode 100644 index 0000000000..42b179f7b6 --- /dev/null +++ b/docs/src/user/testing.tex @@ -0,0 +1,3 @@ +\chapter{Testing Xen} + +Placeholder. -- 2.30.2